// 版权所有2009 Go作者。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

/*
Package hmac implements the Keyed-Hash Message Authentication Code (HMAC) as
defined in U.S. Federal Information Processing Standards Publication 198.
An HMAC is a cryptographic hash that uses a key to sign a message.
The receiver verifies the hash by recomputing it using the same key.

Receivers should be careful to use Equal to compare MACs in order to avoid
timing side-channels:

	// ValidMAC报告messageMAC是否是message的有效HMAC标记。
	func ValidMAC(message, messageMAC, key []byte) bool {
		mac := hmac.New(sha256.New, key)
		mac.Write(message)
		expectedMAC := mac.Sum(nil)
		return hmac.Equal(messageMAC, expectedMAC)
	}
*/
package hmac

import (
	"crypto/subtle"
	"hash"
)

// FIPS 198-1:
// https:

// key被零填充到哈希函数的块大小
// ipad=0x36字节重复密钥长度
// opad=0x5c字节重复密钥长度
// hmac=H（[key^opad]H（[key^ipad]text））

// marshable是编码的组合。二进制封送处理程序和
// 编码。双星解算器。这里重复它们的方法定义是为了避免对编码包的依赖。
type marshalable interface {
	MarshalBinary() ([]byte, error)
	UnmarshalBinary([]byte) error
}

type hmac struct {
	opad, ipad   []byte
	outer, inner hash.Hash

	// 如果marshaled为true，则opad和ipad不包含密钥的填充
	// 副本，而是在
	// opad/ipad输入后，外部/内部的封送状态。
	marshaled bool
}

func (h *hmac) Sum(in []byte) []byte {
	origLen := len(in)
	in = h.inner.Sum(in)

	if h.marshaled {
		if err := h.outer.(marshalable).UnmarshalBinary(h.opad); err != nil {
			panic(err)
		}
	} else {
		h.outer.Reset()
		h.outer.Write(h.opad)
	}
	h.outer.Write(in[origLen:])
	return h.outer.Sum(in[:origLen])
}

func (h *hmac) Write(p []byte) (n int, err error) {
	return h.inner.Write(p)
}

func (h *hmac) Size() int      { return h.outer.Size() }
func (h *hmac) BlockSize() int { return h.inner.BlockSize() }

func (h *hmac) Reset() {
	if h.marshaled {
		if err := h.inner.(marshalable).UnmarshalBinary(h.ipad); err != nil {
			panic(err)
		}
		return
	}

	h.inner.Reset()
	h.inner.Write(h.ipad)

	// 如果基础哈希是可封送的，我们可以通过现在保存哈希状态的副本，并在将来恢复它来节省一些时间
	// 调用重置和求和，而不是每次写入ipad/opad。
	// 
	// 如果其中任何一个哈希值由于任何原因都无法识别，
	// 在这里可以安全地跳出。
	marshalableInner, innerOK := h.inner.(marshalable)
	if !innerOK {
		return
	}
	marshalableOuter, outerOK := h.outer.(marshalable)
	if !outerOK {
		return
	}

	imarshal, err := marshalableInner.MarshalBinary()
	if err != nil {
		return
	}

	h.outer.Reset()
	h.outer.Write(h.opad)
	omarshal, err := marshalableOuter.MarshalBinary()
	if err != nil {
		return
	}

	// 封送成功；保存封送状态以备以后使用
	h.ipad = imarshal
	h.opad = omarshal
	h.marshaled = true
}

// New使用给定的哈希返回一个新的HMAC哈希。散列类型和密钥。
// 像sha256这样的新函数。crypto/sha256中的New可以用作h。
// h必须在每次调用时返回一个新的哈希。
// 注意，与标准库中的其他哈希实现不同，返回的哈希不实现编码。二进制封送处理程序
// 或编码。双星解算器。
func New(h func() hash.Hash, key []byte) hash.Hash {
	hm := new(hmac)
	hm.outer = h()
	hm.inner = h()
	unique := true
	func() {
		defer func() {
			// 如果基础类型不可比，比较可能会恐慌。
			_ = recover()
		}()
		if hm.outer == hm.inner {
			unique = false
		}
	}()
	if !unique {
		panic("crypto/hmac: hash generation function does not produce unique values")
	}
	blocksize := hm.inner.BlockSize()
	hm.ipad = make([]byte, blocksize)
	hm.opad = make([]byte, blocksize)
	if len(key) > blocksize {
		// 如果密钥太大，则将其散列。
		hm.outer.Write(key)
		key = hm.outer.Sum(nil)
	}
	copy(hm.ipad, key)
	copy(hm.opad, key)
	for i := range hm.ipad {
		hm.ipad[i] ^= 0x36
	}
	for i := range hm.opad {
		hm.opad[i] ^= 0x5c
	}
	hm.inner.Write(hm.ipad)

	return hm
}

// Equal在不泄露时间信息的情况下，比较两台Mac的相等性。
func Equal(mac1, mac2 []byte) bool {
	// 如果Mac的长度不同，我们不必是常数时间，因为这表明使用了完全不同的哈希函数
	// 。
	return subtle.ConstantTimeCompare(mac1, mac2) == 1
}
